Skip to content

Modernize the build: remove etstool.py, uv-driven CI, uv_build, uv.lock - #628

Merged
mdickinson merged 49 commits into
mainfrom
remove-etstool
Aug 6, 2026
Merged

mdickinson merged 49 commits into
mainfrom
remove-etstool

Conversation

@mdickinson

@mdickinson mdickinson commented Aug 5, 2026 •

Copy link
Copy Markdown
Member

Towards #630, covering all of its checklist but the last item:

  • Remove etstool.py in favour of direct command invocations
  • Use uv as the primary driver for development and CI tasks
  • Switch from setuptools to uv_build for the build backend; remove
    MANIFEST.in
  • Add a tracked uv.lock
  • Consider switching to src/ layout — left to a follow-up, since moving
    every file would swamp the rest of this PR

What changes

  • etstool.py goes. It was undocumented for human use, and CI used 2 of its
    9 commands — always through a bootstrap Python whose only purpose was to run
    it.
  • uv drives everything except EDM. The documentation, style and test
    requirements become dependency groups in pyproject.toml, replacing
    docs/requirements.txt and style-requirements.txt. test-with-pypi drops
    actions/setup-python entirely.
  • uv.lock is tracked and installed with --locked, so an upstream release
    can no longer break CI, and dependabot's uv ecosystem keeps it current.
  • uv_build replaces setuptools. Package data is picked up automatically,
    so MANIFEST.in and the five [tool.setuptools.package-data] entries go.
  • Platform coverage shifts. EDM drops macOS — no macOS installer is
    published for 4.1.4 or 4.1.5 — and moves to 4.1.5, while test-with-pypi
    gains macOS and Windows, so it now runs 3 OSes × 6 Pythons.
  • ets-from-source moves off EDM to uv add --branch main, which re-locks
    only the four ETS packages and leaves pytest at its pinned version.
  • A toolkit-free smoke test (test-without-toolkit, Ubuntu / 3.14) checks
    that Envisage doesn't accidentally require a GUI toolkit and that the tests
    needing one skip rather than fail: 171 passed, 7 skipped. The EDM workflow
    covers this too, but shouldn't be the only thing that does. pytest and
    pyside6 move into test and gui groups so the job can ask for one without
    the other; dev includes both, so uv run is unchanged everywhere else.

Worth a look

Artifact contents. The wheel was diffed entry-by-entry against the released
8.0.0 wheel on PyPI: identical bar two files, gaining
envisage/ui/tasks/tests/data/README.md (excluded before by a data/*.pkl
glob) and losing setuptools' top_level.txt, which is in no packaging standard.
METADATA is unchanged modulo field order. The sdist loses CHANGES.rst —
nothing consumes it, since no docs/ directory has ever shipped — and gains a
pyproject.toml.orig, which is deliberate uv_build behaviour
(astral-sh/uv#18741).

The EDM jobs now run pytest rather than unittest, so filterwarnings = error
(#619) applies to them for the first time.

Read the Docs was already broken, and this should fix it. .readthedocs.yaml
pinned Python 3.11 while #601 raised Sphinx to 9.1.0, which needs 3.12+, so the
install step failed — see #631. Deliberately no closing keyword: better to
confirm a green RTD build after merge.

publish-on-pypi builds with uv build but still uploads with
pypa/gh-action-pypi-publish.
uv publish uploads PEP 740 attestations but
does not generate them, so using it would have published 8.1.0 without the
provenance 8.0.0 has (PyPI's provenance endpoint: 200 for 8.0.0, 404 for 7.0.4).
The upload step is therefore byte-identical to main's. twine check --strict
is deliberately not restored — a weak check we're happy to lose.

Four things PR CI cannot exercise, since GitHub reads them from the default
branch: ets-from-source and publish-on-pypi (schedule/dispatch only), the
dependabot config, and the Read the Docs config. I dispatched ets-from-source
against this branch — 3/3 green, installing from the ETS main branches.

This PR was created with the assistance of an AI coding agent.

mdickinson and others added 13 commits August 5, 2026 17:35
etstool.py was undocumented for human use and invoked only by the two
EDM-based workflows, both of which drove it through a bootstrap Python
whose sole purpose was to run it. CI used 2 of its 9 commands.

The EDM workflows now call edm directly. EDM ships its own interpreter,
so the bootstrap Python and bootstrap-requirements.txt go with it. The
dependency list moves into the workflow env, which is also what the EDM
package cache key now hashes.

Those jobs move from unittest to pytest, so that filterwarnings = error
applies to them too; it previously covered only the PyPI jobs. They run
from outside the source tree, as etstool.py's tempdir did, so that the
installed package is what gets exercised, with -c supplying the
repository's pytest configuration.

The workflows that don't use EDM now use uv. In the test matrix that
also removes the --ignore-requires-python workaround for PySide6, since
uv does not enforce Requires-Python upper bounds.

Dropped along the way: coverage collection whose output nothing consumed,
a black pin that had drifted from style-requirements.txt, sphinx and
enthought_sphinx_theme installs for a docs command CI never called, and
an unexercised pyqt6 toolkit option.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Replace the uv pip compatibility interface with uv's own project
interface. The documentation, style and test requirement sets move into
pyproject.toml as PEP 735 dependency groups, so docs/requirements.txt and
style-requirements.txt go away.

The workflows now run `uv run --group test`, `--group docs` and
`--only-group style`, which sync the environment as a side effect; no
explicit venv creation or installation step remains. The style checks use
--only-group so that Envisage itself isn't installed to run them.

The pinned Sphinx supports Python 3.12 or later, which is narrower than
Envisage's own range, and a group's requirements have to resolve across
the whole of requires-python. tool.uv.dependency-groups constrains just
that group, which keeps the pins the requirements file had.

uv run and uv lock create .venv and uv.lock in the working tree, so both
are now ignored.

Dependency groups also make PySide6 available on Python 3.15, where the
tests previously skipped the toolkit-dependent cases: 178 pass on both
3.10 and 3.15, against 171 passed and 7 skipped before.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The action's python-version input sets UV_PYTHON itself, so the separate
env blocks were noise. Seven of them go away, and the two style
workflows, both docs workflows and the publish workflow lose their
workflow-level env entirely.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
uv includes the 'dev' group by default, so `uv sync` and a bare `uv run`
give a local checkout everything needed to test and style-check it,
without naming a group.

dev is composed from the existing groups with include-group rather than
replacing them. Merging style and test into one flat group would make the
style jobs install the test group's PySide6 too, which is around 255 MB of
Qt to run Black; --only-group style keeps them at 12 packages.

AGENTS.md now documents uv sync in place of the pip install steps, and its
style commands go back to the bare form, which the dev group makes correct
again.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The dependency-replacement step ran under `shell: bash`, where the edm
wrapper isn't on the path on Windows, so the job failed with
"edm: command not found" before installing anything. A dispatched run
caught it; the weekly cron would otherwise have found it on Friday.

The loop that needed bash is gone. Each removal is now its own step under
the default shell: remove-package takes one package at a time, and a
multi-command run block would only report its last exit status under pwsh,
so a failed removal could pass unnoticed. The four source installs collapse
into a single pip invocation, which also lets the four resolve together
rather than depending on install order.

uv invocations use `uv run -m <module>` in place of
`uv run -- python -m <module>`, and the gh-pages helper runs as a script
rather than through an explicit python.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Bare python isn't necessarily on the path, whereas uv run works wherever
uv is installed, and it syncs the dev group first so the tools it invokes
are present without a separate install step.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
setup-uv keys its cache on
setup-uv-2-{arch}-{image}-{python-version}-{glob-hash}, which includes the
Python version but not what the environment is for. The style, docs and
3.14 test jobs all pin 3.14 on ubuntu with the same pyproject.toml, so all
three computed one key. The caches from the last run show what that costs:
the 3.10-3.13 and 3.15 entries are 242-260MB, while the shared 3.14 entry
is 1MB, having been written by whichever style job won the upload race. The
docs and 3.14 test jobs then hit that cache, find none of their packages in
it, and can't save their own because the key is taken.

A cache-suffix per purpose separates them. Both style workflows share the
'style' suffix, and all three docs workflows share 'docs', which is right:
those do install the same group as each other.

cache-dependency-glob goes away, since the action's default already matches
**/pyproject.toml, and the requirements files it also matches no longer
exist.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
--group is additive to the default groups rather than a restriction, so
`uv run --group test` meant dev plus test, and dev already includes test.
The environments are byte-identical with and without the flag, so
test-with-pypi drops it.

The docs jobs were relying on the same additivity without meaning to: they
got PySide6 from dev, and that toolkit turns out to matter. Building the
documentation without one leaves autodoc resolving the toolkit-dependent
Pyface base classes to 'Unimplemented' and reducing their signatures to
(*args, **kwargs) across 16 API pages, with no warning of any kind. The
docs group therefore declares a toolkit itself, and the docs jobs pass
--no-default-groups so that what they build with is what the group
declares. Verified byte-identical to the previous output.

publish-on-pypi uses uv publish in place of the pypa publish action and
the twine check. Trusted publishing is requested explicitly with 'always'
rather than left to 'automatic', so a missing OIDC token fails at that
step rather than falling back to credentials this workflow doesn't have.
PyPI's trusted publisher is keyed on the workflow filename and
environment, both unchanged.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The step lists the environment's dependency tree; the package under test
is Envisage itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
uv writes a .gitignore containing '*' inside the environment it creates,
so the directory ignores itself.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
How uv treats the 'dev' group isn't specific to this project.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nothing referenced the test group by name once test-with-pypi stopped
passing --group test; it existed only to be included by dev. Its contents
move into dev directly. style stays separate, because the style workflows
select it with --only-group, and docs likewise.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson added a commit that referenced this pull request Aug 6, 2026
Prepares the 8.0.0 release:

* Add `Released: 2026-08-06` and an overview to the 8.0.0 changelog
section,
  following the style used for earlier major releases.
* Credit contributors since 7.0.4 under `Thanks to`.
* Bump the version in `pyproject.toml` from 7.0.4 to 8.0.0.

The changelog already accounts for every PR merged since the 7.0.4 tag,
so no
new entries were needed. #628 is deliberately excluded: it is still
open, and
we would rather not change the CI machinery immediately before a major
release. Its changelog entries will need re-filing under a later version
once
it merges.

*This PR was created with the assistance of an AI coding agent.*

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson and others added 5 commits August 6, 2026 09:59
8.0.0 shipped without this branch, so its entries no longer belong in
that section.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A literal "YYYY-MM-DD" is harder to overlook at release time than a
missing line.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Nothing has referenced it since coverage reporting left CI in #288.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
uv_build includes everything under the package directory in the wheel,
so the per-subpackage package-data lists go, and MANIFEST.in with them.

The wheel's file list is unchanged apart from two entries: it gains
envisage/ui/tasks/tests/data/README.md, which the data/*.pkl glob had
excluded from beside its own pickles, and loses the setuptools-specific
top_level.txt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mdickinson mdickinson changed the title Remove etstool.py, and use uv in the workflows that don't use EDM Modernize the build: remove etstool.py, use uv in the non-EDM workflows, switch to uv_build Aug 6, 2026
mdickinson and others added 2 commits August 6, 2026 10:32
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The workflows that use uv now pass --locked, which both installs the
pinned versions and fails if uv.lock is stale with respect to
pyproject.toml. An upstream release can no longer break CI on its own.

That also removes the early warning the unlocked resolution gave us, so
a new weekly workflow runs the same matrix with --upgrade to get it back.
It is scheduled rather than per-PR, so an upstream break reports without
blocking merges.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mdickinson mdickinson changed the title Modernize the build: remove etstool.py, use uv in the non-EDM workflows, switch to uv_build Modernize the build: remove etstool.py, uv-driven CI, uv_build, uv.lock Aug 6, 2026
mdickinson and others added 2 commits August 6, 2026 10:43
Dependabot's uv ecosystem updates uv.lock, so lock refreshes don't have
to be done by hand. Weekly with a 7-day cooldown, matching the existing
github-actions entry.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A dependabot lock bump already runs the full matrix against the new
versions, and arrives with the fix in it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mdickinson
mdickinson marked this pull request as draft August 6, 2026 09:58
mdickinson and others added 3 commits August 6, 2026 10:59
They were split by the black, isort and pytest config. Both now sit at
the end, preserving the rough alphabetical order of the tool tables.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
MANIFEST.in included it and source-include carried that over, but
nothing consumes it from an sdist: the docs build reads it from a
checkout, and the sdist has no docs directory.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
.readthedocs.yaml still installed docs/requirements.txt, which this
branch deleted, so Read the Docs builds would have failed at the install
step. It now uses uv with the docs group. The Python version goes to
3.14 because that group requires 3.12 or later.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson and others added 9 commits August 6, 2026 13:05
It was added in #454 to stop test hangs with PySide2 on macOS 11.
PySide2 hasn't been in the matrix for some time.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
There is no macOS installer for 4.1.4 or 4.1.5 --
edm_cli_4.1.5_osx_x86_64.pkg 403s -- so the macOS jobs can't install it.
4.1.3 is the newest version published for all three platforms.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Each matrix job gets its own runner, so there is nothing for the
per-runtime, per-toolkit name to disambiguate.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
EDM no longer supports macOS: no osx installer is published for 4.1.4 or
4.1.5. With macOS out of the matrix, 4.1.5 is available everywhere the
workflow now runs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
fail-fast is off so that one platform's failure doesn't hide the others.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Drop the unittest runner, and the per-file, per-class and per-method
pytest invocations: standard pytest usage an agent already knows. What
was left of the prose duplicated the two sections above it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Eight entries become two. The rest -- .coveragerc, the EDM version and
matrix, the ets-from-source internals, the Read the Docs config -- is CI
plumbing that nobody reads a changelog to find.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mdickinson
mdickinson requested a review from Copilot August 6, 2026 12:54
@mdickinson
mdickinson marked this pull request as ready for review August 6, 2026 12:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR modernizes Envisage’s build and CI pipeline by removing the legacy etstool.py workflow, adopting uv as the primary environment/task driver, switching the build backend to uv_build, and introducing a tracked uv.lock to make dependency resolution reproducible across CI and development.

Changes:

  • Replace setuptools with uv_build and remove legacy packaging configuration (MANIFEST.in, setuptools package-data entries).
  • Move docs/style/dev requirements into pyproject.toml dependency groups and update CI / RTD / publishing workflows to use uv.
  • Add and rely on a committed uv.lock (with CI enforcing locked installs).

Reviewed changes

Copilot reviewed 20 out of 21 changed files in this pull request and generated 6 comments.

Show a summary per file
File Description
uv.lock Adds a tracked uv lockfile for reproducible installs.
pyproject.toml Switches build backend to uv_build and defines dependency groups for docs/style/dev.
MANIFEST.in Removes explicit sdist include list (now handled by uv_build).
etstool.py Removes legacy EDM/click-based task runner.
docs/requirements.txt Removes docs requirements file in favor of dependency groups.
CHANGES.rst Adds release notes for the build/CI modernization.
AGENTS.md Updates contributor guidance to use uv run/uv sync/uv lock.
.readthedocs.yaml Updates RTD config to use uv and a newer Ubuntu image / Python.
.github/workflows/update-gh-pages.yml Updates gh-pages docs workflow to use uv.
.github/workflows/update-gh-pages-on-release.yml Updates release gh-pages docs workflow to use uv.
.github/workflows/test-with-pypi.yml Expands OS coverage and migrates PyPI-based testing to uv.
.github/workflows/test-with-edm.yml Removes reliance on etstool.py and runs pytest directly under EDM.
.github/workflows/test-doc-build.yml Migrates doc build CI to uv-based invocation.
.github/workflows/style-requirements.txt Removes style requirements file in favor of dependency groups.
.github/workflows/publish-on-pypi.yml Migrates packaging/publishing steps to uv build / uv publish.
.github/workflows/ets-from-source.yml Migrates source-branch dependency testing to uv and uv add --branch main.
.github/workflows/check-style.yml Migrates style checks to uv execution.
.github/workflows/check-style-strict.yml Migrates strict style checks (copyright) to uv execution.
.github/workflows/bootstrap-requirements.txt Removes bootstrap requirements file (click no longer needed).
.github/dependabot.yml Adds Dependabot support for the uv ecosystem/lockfile updates.
.coveragerc Removes coverage configuration formerly used by etstool.py-driven runs.
Suppressed comments (1)

CHANGES.rst:21

  • This entry cites #628, but this PR/issue work is described as closing #630. The reference should be updated so the changelog points at the right tracker context.
* Build with the ``uv_build`` backend in place of ``setuptools``. Files
  inside the package are included in the wheel automatically, so
  ``MANIFEST.in`` and the explicit ``package-data`` configuration are no
  longer needed. The source distribution no longer includes
  ``CHANGES.rst``. (#628)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread CHANGES.rst Resolved
Comment thread CHANGES.rst Resolved
Comment thread .github/workflows/test-with-pypi.yml Resolved
Comment thread .github/workflows/publish-on-pypi.yml Resolved
Comment thread .github/workflows/update-gh-pages.yml Resolved
mdickinson and others added 7 commits August 6, 2026 14:13
It lived in .github/workflows/, not the repository root, which the bare
name implied next to a fully-qualified docs/requirements.txt.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
uv publish uploads PEP 740 attestations but doesn't generate them, so
switching to it would have shipped 8.1.0 without the provenance 8.0.0
has. Building still uses uv build, which writes to dist/ -- what the
action uploads by default.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Envisage must keep working with no GUI toolkit installed, and the tests
that need one must skip rather than fail. A single Ubuntu / 3.14 job
covers that; the EDM workflow tests it too, but shouldn't be the only
thing that does.

pytest moves into its own test group so the job can ask for it without
pyside6; dev includes that group, so uv run is unchanged elsewhere.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
It was declared in both docs and dev, for different reasons: docs needs a
toolkit so autodoc resolves Pyface's base classes, dev needs one to run
the GUI tests. One group means one place to constrain or change it.

Named gui rather than toolkit because the null toolkit is also a toolkit;
what these two consumers need is specifically a graphical one.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The paragraph still said dev "provides pytest and PySide6 and includes
the style group", which predates the test and gui groups.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@mdickinson
mdickinson merged commit 0d81eb2 into main Aug 6, 2026
26 checks passed
@mdickinson
mdickinson deleted the remove-etstool branch August 6, 2026 15:04
mdickinson added a commit that referenced this pull request Aug 7, 2026
Closes #631.

## The Read the Docs failure

#628 fixed the Python version pin that broke the 8.0.0 docs build, and a
`latest` build did run against `main` afterwards — but it still failed,
for a
new and unrelated reason. It gets 26% of the way through reading sources
and
dies at `api/envisage.plugins.python_shell.view.api`:

```
qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
This application failed to start because no Qt platform plugin could be initialized.
```

The cause: #628 added `pyside6` to the `docs` dependency group, so that
autodoc
sees a real toolkit. Autodoc then imports `pyface.toolkit`, and
importing
Pyface's toolkit *constructs a `QApplication`*. That needs a working
platform
plugin, and Read the Docs builds have no display, so Qt calls `qFatal`
and
aborts `sphinx-build`.

Asking for the `offscreen` platform in `docs/source/conf.py` fixes it.
That
runs before any autodoc import, and `setdefault` leaves an explicit
choice
alone, so it also fixes local headless builds without taking the option
away.

## The same fix removes the X11 packages from CI

The `install-qt-support` action `apt-get`s eight `libxcb`/`libxkbcommon`
packages, and those are needed by the **xcb** platform plugin
specifically —
which is exactly what `offscreen` doesn't use. The remaining two,
`libegl1`
and `libopengl0`, are linked by `libQt6Gui` rather than by the platform
plugin, so they may still be needed; this PR removes them too, on the
basis
that CI is the cheapest way to find out. If the Linux jobs fail on a
missing
library, the fix is to add back just that one.

With `QT_QPA_PLATFORM=offscreen` set, `xvfb-run -a` is redundant too,
and the
`Run tests (Ubuntu)` / `Run tests (not Ubuntu)` split collapses into a
single
step in all three test workflows.

**A judgement call worth reviewing:** `QT_QPA_PLATFORM` is set at the
workflow
level, so it applies to the macOS and Windows runners as well, not just
Linux.
That keeps the workflows uniform and is what lets the split steps
collapse,
but it does mean CI no longer exercises the native `cocoa` and `windows`
platform plugins. Happy to restrict it to Linux instead if you'd rather
keep
that coverage.

## Verification

Locally, on macOS:

* the full docs build succeeds from an environment with no Qt variables
set,
  producing 138 source files and zero warnings;
* the test suite passes identically with and without
  `QT_QPA_PLATFORM=offscreen` (178 passed each way);
* `ruff check` and `ruff format --check` are clean.

What can't be checked locally is whether the Linux jobs survive losing
the
`apt-get` step — that's what this PR's CI run is for. Whether Read the
Docs
actually goes green can only be confirmed from a `latest` build after
this
merges.

## Two things this PR does *not* fix

* `stable` and `8.0.0` will stay broken. Read the Docs reads
`.readthedocs.yaml` from the version being built, and the 8.0.0 tag
still
  carries the old Python 3.11 pin, so that tag can never build. Both
  `/en/latest/` and `/en/stable/` are currently serving the March 2023
  output — the changelog on both tops out at *Version 7.0.1* — and
  `/en/8.0.0/` is a 404. Fixing `latest` restores the URL users land on,
since that's the project's default version, but `stable` needs a release
  tag that carries the fixed configuration.
* `test-doc-build.yml` isn't reproducing Read the Docs. It builds the
docs on
`ubuntu-latest` with PySide6 installed, no X11 packages and no
`xvfb-run`,
and it passes — so it wasn't catching this. Worth a follow-up issue to
work
  out why the runner tolerates what Read the Docs doesn't.

*This PR was created with the assistance of an AI coding agent.*

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson added a commit that referenced this pull request Aug 7, 2026
…648)

Closes #647. Closes #646.

#645 removed the `install-qt-support` action entirely, on the evidence
that
every check stayed green without it. That evidence was misleading — the
checks
stayed green because the GUI tests stopped running.

| Workflow (ubuntu-latest) | Before #645 | After #645 | With this PR |
| --- | --- | --- | --- |
| `test-with-pypi` | 178 passed | 171 passed, **7 skipped** | 178 passed
|
| `test-with-edm` (pyside6) | 178 passed | 171 passed, **7 skipped** |
178 passed |

## What was actually going on

`libEGL.so.1` is a link-time dependency of `libQt6Gui`, so without
`libegl1`
PySide6 can't be imported at all. Pyface handles that by falling back to
its
null toolkit — a *silent* failure. `GUI()` then raises
`NotImplementedError`,
`gui_available` becomes `False`, and every `@requires_gui` test skips
while
the suite reports success.

So the ten packages fell into two categories. The eight
`libxcb`/`libxkbcommon` ones serve the **xcb platform plugin**, and
`QT_QPA_PLATFORM=offscreen` really does make those redundant. The other
two
are needed to import Qt at all, and have to come back:

* `libegl1` — a link-time dependency of `libQt6Gui`, needed everywhere.
* `libopengl0` — needed by EDM's PySide6 build, though not by the PyPI
wheel. This is what the original action's `PYSIDE-1547` comment was
about.

Two packages instead of ten, and `xvfb-run` stays gone.

The second one was found the hard way, and is a good advertisement for
the
new test: with only `libegl1`, `test-with-edm (ubuntu, pyside6)` failed
on
the guard while the rest of the suite reported `171 passed, 7 skipped`.
That
environment had been quietly skipping its GUI tests too, and nothing
else in
CI would have said so.

## The same missing library was breaking the documentation (#646)

`test-doc-build.yml` and both `update-gh-pages` workflows build on
`ubuntu-latest` with no Qt packages, so Sphinx got the null toolkit too.
Autodoc only imports classes and never instantiates them, and the null
toolkit's placeholder raises only on instantiation — so the build
succeeds
while documenting placeholders.

That is live on the published documentation today, on two of 116 API
pages:

*
[`python_shell_view`](https://docs.enthought.com/envisage/api/envisage.plugins.python_shell.view.python_shell_view.html)
— `Bases: Unimplemented`
*
[`namespace_view`](https://docs.enthought.com/envisage/api/envisage.plugins.python_shell.view.namespace_view.html)
— `Bases: Unimplemented`

It's long-standing rather than new: `/envisage/7.0/` and
`/envisage/8.0/` show
it too, so #628's "a toolkit is needed for accurate API documentation
from
autodoc" never took effect on a runner. Adding the action to those
workflows
fixes it. `update-gh-pages.yml` runs on push to `main`, so the root
documentation self-corrects when this merges; the versioned `8.0/` copy
would
need a manual `workflow_dispatch` if it's worth correcting.

This also makes `test-doc-build.yml` a real guard for #631-style
breakage.
`QT_QPA_PLATFORM` is deliberately *not* set in that workflow, so it
exercises
the same `conf.py` fallback Read the Docs relies on. Verified on a
runner:
with `libegl1` installed and `QT_QPA_PLATFORM` unset, the #631 abort
reproduces verbatim — `Could not load the Qt platform plugin "xcb"`.

## The new test

`test_support.py` fails, rather than skipping, when PySide6 is
importable as a
package but Pyface still ends up on the null toolkit. That's the check
that
would have caught #645 immediately. It skips when no toolkit is
installed (so
`test-without-toolkit` is unaffected) and when `ETS_TOOLKIT=null` is set
deliberately. Drop it if you'd rather not have it — the rest of the PR
stands
on its own.

## Verification

All 26 checks pass. `test-with-pypi` and `test-with-edm` are both back
to
`179 passed` with **no skips** on ubuntu (179 rather than 178 because of
the
new test), and `test-without-toolkit` still skips as it should.

Isolated on an `ubuntu-latest` runner beforehand, with `libegl1` as the
only
added package: `PySide6 imports fine`, `platformName: offscreen`,
`gui_available: True`, full suite `178 passed` with no skips, and the
documentation build resolving the real Qt `PythonShell`. With
`QT_QPA_PLATFORM` unset, the same runner reproduced the #631 abort
verbatim.

Locally: the guard skips rather than fails under `ETS_TOOLKIT=null`, and
ruff
is clean.

*This PR was created with the assistance of an AI coding agent.*

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
mdickinson added a commit that referenced this pull request Aug 7, 2026
Closes #653.

Prepares the 8.0.1 release:

* Retitle the in-development changelog section from `8.1.0` to `8.0.1`,
and
  replace the `Released: YYYY-MM-DD` placeholder with today's date.
* Add the overview, in the style used for earlier bugfix releases, and
credit
  contributors since 8.0.0 under `Thanks to`.
* Bump the version in `pyproject.toml` from 8.0.0 to 8.0.1, and refresh
  `uv.lock`, which pins the project's own version. (8.0.0 predated the
  lockfile, so this step is new since the last release.)

Three PRs merged since the 8.0.0 tag had no changelog entry, so this
adds
them: the ruff reformat (#642), folded into the entry for the PR that
configured ruff (#637), the `edm.yaml` move (#634), and the
`pypa/gh-action-pypi-publish` bump (#633). #650 is deliberately left
out,
since it only edited the changelog. Happy to drop #633 and #634 if you'd
rather keep the release notes to things a reader of them would act on.

Pre-flight, beyond CI: `uv build` and `twine check --strict` both pass,
and
`uv sync --locked` confirms the refreshed lockfile.

Diffing the 8.0.1 artifacts against the released 8.0.0 ones shows one
difference that isn't explained by the changes since 8.0.0: the sdist
now
carries a `pyproject.toml.orig` beside a `pyproject.toml` that has been
rewritten and stripped of its comments. That is `uv_build` working as
designed — since uv 0.12.0 it always rewrites the sdist's
`pyproject.toml`
as TOML 1.0, so that older build frontends can consume it, and preserves
the
original alongside. The two parse to identical data. It arrived with
#628,
along with the switch to `uv_build`, and needs no action.

*This PR was created with the assistance of an AI coding agent.*

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants